Differences between PicketLink v2.1 and v2.0

Configuration Changes

This article will list out all the differences that have been introduced into PicketLink v2.1 as compared to v2.0

Configuration Changes

PicketLink v2.1 comes with some improvements in the configuration of Identity Providers and Service Providers. One of the main objectives in this version is made PicketLink even more easier to use.

Consolidated configuration file: picketlink.xml

Previously, PicketLink configuration was done in multiple configuration files:

WEB-INF/picketlink-idfed.xml: PicketLink IDP/SP configurations.
WEB-INF/picketlink-handlers.xml : PicketLink handlers. Additional processing of SAML requests and responses.
WEB-INF/picketlink-sts.xml: Security Token Service and SAML configurations.

Now, you can just use one configuration file:

WEB-INF/picketlink.xml: Consolidated configuration file.

Basically, the picketlink.xml file groups all the configurations files in one single file. Bellow is an example of a picketlink.xml file used to configure an IDP:

<PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">
    <PicketLinkIDP xmlns="urn:picketlink:identity-federation:config:2.1"> 
        <IdentityURL>http://localhost:8080/idp/</IdentityURL> 
        <Trust> 
            <Domains>localhost,jboss.com,jboss.org,amazonaws.com</Domains> 
        </Trust> 
    </PicketLinkIDP> 
    <Handlers xmlns="urn:picketlink:identity-federation:handler:config:2.1"> 
        <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2IssuerTrustHandler" /> 
        <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2LogOutHandler" /> 
        <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2AuthenticationHandler" /> 
        <Handler class="org.picketlink.identity.federation.web.handlers.saml2.RolesGenerationHandler" /> 
    </Handlers>
</PicketLink>

Now, let's look how a Service Provider configuration looks like:

<PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">
    <PicketLinkSP xmlns="urn:picketlink:identity-federation:config:2.1"
         ServerEnvironment="tomcat"
         BindingType="REDIRECT"
         RelayState="someURL"
         ErrorPage="/someerror.jsp"
         IDPUsesPostBinding="true"
         SupportsSignatures="true">

        <IdentityURL>http://localhost:8080/idp/</IdentityURL>
        <ServiceURL>http://localhost:8080/employee/</ServiceURL>
    </PicketLinkSP>

    <Handlers xmlns="urn:picketlink:identity-federation:handler:config:2.1">
        <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2IssuerTrustHandler" />
        <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2LogOutHandler" />
        <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2AuthenticationHandler" />
        <Handler class="org.picketlink.identity.federation.web.handlers.saml2.RolesGenerationHandler" />
    </Handlers>
</PicketLink>

Note that the PicketLink configuration namespace has changed to 2.1. Eg.: urn:picketlink:identity-federation:config:2.1.

Unique Valve at the Service Provider (org.picketlink.identity.federation.bindings.tomcat.sp.ServiceProviderAuthenticator)

Previously we had four flavors of Service Provider authenticators:

org.picketlink.identity.federation.bindings.tomcat.sp.SPPostFormAuthenticator : SAML HTTP POST Binding
org.picketlink.identity.federation.bindings.tomcat.sp.SPPostSignatureFormAuthenticator: SAML HTTP POST Binding with Signature Support
org.picketlink.identity.federation.bindings.tomcat.sp.SPRedirectFormAuthenticator : SAML HTTP Redirect Binding
org.picketlink.identity.federation.bindings.tomcat.sp.SPRedirectSignatureAuthenticator : SAML HTTP Redirect Binding with Signature Support

Now, you can just use one single authenticator:

org.picketlink.identity.federation.bindings.tomcat.sp.ServiceProviderAuthenticator

Now, the only configuration you need in jboss-web.xml is:

<?xml version="1.0" encoding="UTF-8"?>
<jboss-web> 
    <security-domain>sp</security-domain> 
    <context-root>employee</context-root> 
    <valve> 
        <class-name>org.picketlink.identity.federation.bindings.tomcat.sp.ServiceProviderAuthenticator</class-name> 
    </valve>
</jboss-web>

For JBoss AS5 and Apache Tomcat 6 this configuration is located in the context.xml file.

Is the previously configuration still supported ?

Yes. The previously configuration is supported, but it is now marked as DEPRECATED.

Please, prefer the new configuration for upgrading or creating new projects using PicketLink.